---
title: gluestack-ui Grid Component | Installation, Usage, and API

description: Utilize a versatile layout tool for creating grid-based UIs with rows and columns. Flexible and robust for diverse layout structures.

pageTitle: Grid

pageDescription: Utilize a versatile layout tool for creating grid-based UIs with rows and columns. Flexible and robust for diverse layout structures.

showHeader: true

tag: alpha RSC
---

import { Meta } from '@storybook/addon-docs';

<Meta title="with-nativewind/Components/Layout/Grid" />

import Wrapper from '../../core-components/nativewind/Wrapper';
import { transformedCode } from '../../utils';
import {Grid, GridItem} from '../../core-components/nativewind/grid';
import {Text} from '../../core-components/nativewind/text';
import {
  AppProvider,
  CodePreview,
  Table,
  TableContainer,
  InlineCode,
  AddIcon,
  InfoIcon,
  Alert,
  Tabs,
  CollapsibleCode
} from '@gluestack/design-system';


This is an illustration of **Grid** component.

<Wrapper>
  <CodePreview
      showComponentRenderer={ true }
    showArgsController={ false}
    _rendererWrapper={{
      alignItems: 'stretch',
      padding: 20,
    }}
    metaData = {{
      code: `
<Grid className="gap-5" _extra={{
  className: 'grid-cols-8'
}} >
      <GridItem
        className="bg-background-50 p-6 rounded-md"
        _extra={{
  className: 'col-span-3'
}}
      />
      <GridItem
        className="bg-background-50 p-6 rounded-md"
        _extra={{
  className: 'col-span-5'
}}
      />
      <GridItem
        className="bg-background-50 p-6 rounded-md"
        _extra={{
   className: 'col-span-6'
}}
      />
      <GridItem
        className="bg-background-50 p-6 rounded-md"
        _extra={{
     className: 'col-span-4'
}}
      />
      <GridItem
        className="bg-background-50 p-6 rounded-md"
        _extra={{
   className: 'col-span-4'
}}
      />
    </Grid>
`,
        transformCode: (code) => {
          return transformedCode(code);
        },
          scope: {
        Wrapper,
        Grid,
        GridItem,
        },
      argsType: { },
    }
  }
  />
</Wrapper>

<br />

## Installation

<Tabs value="cli" type="section">
<Tabs.TabList>
      <Tabs.Tab value="cli">
        <Tabs.TabTitle>CLI</Tabs.TabTitle>
      </Tabs.Tab>
     <Tabs.Tab value="manual">
        <Tabs.TabTitle>Manual</Tabs.TabTitle>
     </Tabs.Tab>
  </Tabs.TabList>
  <Tabs.TabPanels>
    <Tabs.TabPanel value="cli">
<>

### Run the following command:
  ```bash
  npx gluestack-ui add grid
  ```
</>
    </Tabs.TabPanel>
    <Tabs.TabPanel value="manual"> 
<>

### Step 1: Copy and paste the following code into index.tsx in your project.
<CollapsibleCode>

```jsx 
%%-- File: core-components/nativewind/grid/index.tsx --%% 
```
</CollapsibleCode>

> Note: **Step 2 is optional and only required if you want to add support for [React Server Components](https://vercel.com/blog/understanding-react-server-components), You can skip this and jump to Step 3 directly if you don't have this requirement.**

### Step 2(optional): Copy and paste the following code into index.web.tsx in your project.
<CollapsibleCode>

```jsx 
%%-- File: core-components/nativewind/grid/index.web.tsx --%% 
```
</CollapsibleCode>

### Step 3: Copy and paste the following code into styles.tsx in your project.
<CollapsibleCode>

```jsx 
%%-- File: core-components/nativewind/grid/styles.tsx --%% 
```
</CollapsibleCode>

### Step 4: Update the import paths to match your project setup.
</>
    </Tabs.TabPanel>
  </Tabs.TabPanels>
</Tabs>

## API Reference

To use this component in your project, include the following import statement in your file.

```jsx
import { Grid, GridItem } from '@/components/ui/grid';
```

```jsx
export default () => (
<Grid >
<GridItem />
</Grid>
);
```

> Note: Our responsive grid component is based on a 12-column grid layout. It follows the CSS **grid system** on the web and **flexbox layout** on native devices. Since the grid layout is only supported on the web, passing the grid-cols and col-span classNames inside _extra is **recommended** for the grid component to work effortlessly on both web and native. Our grid component currently does not support rowSpan.


### Component Props

This section provides a comprehensive reference list for the component props, detailing descriptions, properties, types, and default behavior for easy project integration.

### Grid

It inherits all the properties of React Native's [View](https://reactnative.dev/docs/view) component on native and html div tag on web.

<>
  <TableContainer>
    <Table>
      <Table.THead>
        <Table.TR>
          <Table.TH>
            <Table.TText>Prop</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Type</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Default</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Description</Table.TText>
          </Table.TH>
        </Table.TR>
      </Table.THead>
      <Table.TBody>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>_extra</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>object</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>-</Table.TText>
          </Table.TD>
             <Table.TD>
            <Table.TText>{`Accepts grid-cols-* className. Value for * can range from 1 to 12. Default value is grid-cols-12.`}</Table.TText>
          </Table.TD>
        </Table.TR>
      </Table.TBody>
    </Table>
  </TableContainer>
</>

### GridItem

It inherits all the properties of React Native's [View](https://reactnative.dev/docs/view) component on native and html div tag on web.

<>
  <TableContainer>
    <Table>
      <Table.THead>
        <Table.TR>
          <Table.TH>
            <Table.TText>Prop</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Type</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Default</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Description</Table.TText>
          </Table.TH>
        </Table.TR>
      </Table.THead>
      <Table.TBody>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>_extra</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>object</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>-</Table.TText>
          </Table.TD>
             <Table.TD>
            <Table.TText>{`Accepts col-span-* className. Value for * can range from 1 to 12. Default value is col-span-1.`}</Table.TText>
          </Table.TD>
        </Table.TR>
      </Table.TBody>
    </Table>
  </TableContainer>
</>


## Examples

The Examples section provides visual representations of the different variants of the component, allowing you to quickly and easily determine which one best fits your needs. Simply copy the code and integrate it into your project.

### Setting the gap between grid items

Use the gap-* utilities to change the gap between both rows and columns in grid

<Wrapper>
  <CodePreview
    showComponentRenderer={true}
    showArgsController={false}
    _rendererWrapper={{
      alignItems: 'stretch',
      padding: 20,
    }}
    metaData={{
      code: `
    <Grid className="gap-4" _extra={{
      className: 'grid-cols-9',
    }}>
      <GridItem
        className="bg-background-50 p-3 rounded-md text-center"
        _extra={{
      className: 'col-span-3',
    }}
      >
        <Text>A</Text>
      </GridItem>
       <GridItem
        className="bg-background-50 p-3 rounded-md text-center"
        _extra={{
      className: 'col-span-3',
    }}
      >
        <Text>B</Text>
      </GridItem>
      <GridItem
        className="bg-background-50 p-3 rounded-md text-center"
        _extra={{
      className: 'col-span-3',
    }}
      >
        <Text>C</Text>
      </GridItem>
    </Grid>
      `,
      transformCode: (code) => {
        return transformedCode(code);
      },
      scope: {
       Grid,
        GridItem,
        Text,
        Wrapper,
      },
    }}
  />
</Wrapper>

### Changing row and column gaps independently

Use the gap-x-* and gap-y-* utilities to change the gap between columns and rows independently.

<Wrapper>
  <CodePreview
      showComponentRenderer={ true }
    showArgsController={ false}
    _rendererWrapper={{
      alignItems: 'stretch',
      padding: 20,
    }}
    metaData = {{
      code: `
<Grid className="gap-y-2 gap-x-4" _extra={{
  className: 'grid-cols-6',
}}>
      <GridItem
        className="bg-background-50 p-4 rounded-md text-center"
        _extra={{
          className: 'col-span-2',
        }}
      >
        <Text className="text-sm">01</Text>
      </GridItem>
      <GridItem
        className="bg-background-50 p-4 rounded-md text-center"
         _extra={{
          className: 'col-span-2',
        }}
      >
        <Text className="text-sm">02</Text>
      </GridItem>
      <GridItem
        className="bg-background-50 p-4 rounded-md text-center"
         _extra={{
          className: 'col-span-2',
        }}
      >
        <Text className="text-sm">03</Text>
      </GridItem>
      <GridItem
        className="bg-background-50 p-4 rounded-md text-center"
         _extra={{
          className: 'col-span-2',
        }}
      >
        <Text className="text-sm">04</Text>
      </GridItem>
      <GridItem
        className="bg-background-50 p-4 rounded-md text-center"
         _extra={{
          className: 'col-span-2',
        }}
      >
        <Text className="text-sm">05</Text>
      </GridItem>
            <GridItem
        className="bg-background-50 p-4 rounded-md text-center"
         _extra={{
          className: 'col-span-2',
        }}
      >
        <Text className="text-sm">06</Text>
      </GridItem>
    </Grid>
`,
        transformCode: (code) => {
          return transformedCode(code);
        },
          scope: {
        Wrapper,
        Grid,
        GridItem,
        Text,
        },
      argsType: { },
    }
  }
  />
</Wrapper>

### Nested Grids

The following example depicts how easily you can nest grids to create complex layouts with multiple levels of nesting.

<Wrapper>
  <CodePreview
      showComponentRenderer={ true }
    showArgsController={ false}
    _rendererWrapper={{
      alignItems: 'stretch',
      padding: 20,
    }}
    metaData = {{
      code: `
<Grid className="gap-3" _extra={{
  className: 'grid-cols-8',
}}>
      <GridItem
        className="bg-background-50 p-3 rounded-md text-center"
        _extra={{
          className: 'col-span-4',
        }}
      >
        <Text className="text-sm">01</Text>
      </GridItem>
      <GridItem
        className="bg-background-50 p-3 rounded-md text-center"
         _extra={{
          className: 'col-span-4',
        }}
      >
        <Text className="text-sm">02</Text>
      </GridItem>
      <GridItem
        className="bg-background-50 p-3 rounded-md text-center"
           _extra={{
          className: 'col-span-4',
        }}
      >
      <Grid className="gap-5" _extra={{
        className: 'grid-cols-2',
      }}>
        <GridItem className="bg-background-200 p-2 rounded-md" _extra={{
          className: 'col-span-1',
        }}><Text className="text-sm">1</Text></GridItem>
        <GridItem className="bg-background-200 p-2 rounded-md" _extra={{
          className: 'col-span-1',
        }}><Text className="text-sm" >2</Text></GridItem>
        <GridItem className="bg-background-200 p-2 rounded-md"  _extra={{
          className: 'col-span-1',
        }}><Text className="text-sm">3</Text></GridItem>
             <GridItem className="bg-background-200 p-2 rounded-md" _extra={{
          className: 'col-span-1',
        }}><Text className="text-sm" >4</Text></GridItem>
        </Grid>
      </GridItem>
      <GridItem
        className="bg-background-50 p-3 rounded-md text-center"
        _extra={{
          className: 'col-span-4',
        }}
      >
        <Grid className="gap-5" _extra={{
          className: 'grid-cols-4',
        }}>
        <GridItem className="bg-background-200 p-2 rounded-md" _extra={{
          className: 'col-span-4',
        }}><Text className="text-sm" >1</Text></GridItem>
        <GridItem className="bg-background-200 p-2 rounded-md" _extra={{
          className: 'col-span-4',
        }}><Text className="text-sm">2</Text></GridItem>
        </Grid>
      </GridItem>
    </Grid>
`,
        transformCode: (code) => {
          return transformedCode(code);
        },
          scope: {
        Wrapper,
        Grid,
        GridItem,
        Text,
        },
      argsType: { },
    }
  }
  />
</Wrapper>

### Responsive Grids

You can pass different grid-cols-* and col-span-* values at different breakpoints to create a more responsive layout.

<Wrapper>
  <CodePreview
      showComponentRenderer={ true }
    showArgsController={ false}
    _rendererWrapper={{
      alignItems: 'stretch',
      padding: 20,
    }}
    metaData = {{
      code: `
<Grid className="gap-y-2 gap-x-4" _extra={{
  className: 'grid-cols-6',
}}>
      <GridItem
        className="bg-background-50 p-4 rounded-md text-center"
        _extra={{
          className: 'col-span-6 md:col-span-3 lg:col-span-2',
        }}
      >
        <Text className="text-sm">01</Text>
      </GridItem>
      <GridItem
        className="bg-background-50 p-4 rounded-md text-center"
         _extra={{
  className: 'col-span-6 md:col-span-3 lg:col-span-2',
        }}
      >
        <Text className="text-sm">02</Text>
      </GridItem>
      <GridItem
        className="bg-background-50 p-4 rounded-md text-center"
         _extra={{
    className: 'col-span-6 md:col-span-3 lg:col-span-2',
        }}
      >
        <Text className="text-sm">03</Text>
      </GridItem>
      <GridItem
        className="bg-background-50 p-4 rounded-md text-center"
         _extra={{
        className: 'col-span-6 md:col-span-3 lg:col-span-2',
        }}
      >
        <Text className="text-sm">04</Text>
      </GridItem>
      <GridItem
        className="bg-background-50 p-4 rounded-md text-center"
         _extra={{
      className: 'col-span-6 md:col-span-3 lg:col-span-2',
        }}
      >
        <Text className="text-sm">05</Text>
      </GridItem>
            <GridItem
        className="bg-background-50 p-4 rounded-md text-center"
         _extra={{
        className: 'col-span-6 md:col-span-3 lg:col-span-2',
        }}
      >
        <Text className="text-sm">06</Text>
      </GridItem>
    </Grid>
`,
        transformCode: (code) => {
          return transformedCode(code);
        },
          scope: {
        Wrapper,
        Grid,
        GridItem,
        Text,
        },
      argsType: { },
    }
  }
  />
</Wrapper>

### Why we introduced \_extra prop?

Grid Layout is not supported in native. In order to make our component universal, we introduced the `_extra` prop to pass the grid classnames to the grid component. We use the `_extra` prop to pass the grid classnames to the grid component & extract the neccessary styles from the provided classname. This approach provides a SSR friendly solution for responsiveness.